<html>
<head>
<meta http-equiv=Content-Type content="text/html; charset=windows-1252">
<title>Phemto  -pye - a tiny editor for a tiny environment written in python</title>
<style>
h1,h2,h3 {margin:2 0 8 0}
body     {margin-left:15}
ul       {margin:1}
pre      {margin:1}
th       {font-family:monospace}
sup.h    {color:green;cursor:help;font-weight:bold;font-family:serif}
a.h      {color:green;font-weight:bold;font-family:serif;text-decoration:none}
i        {font-style:normal;font-weight:bold;font-family:courier}
#topBtn {
    display: none;          /* Hidden by default */
    position: fixed;        /* Fixed/sticky position */
    bottom: 55px;           /* Place the button from the bottom */
    right: 10px;            /* Place the button from the right */
    z-index: 99;            /* Make sure it does not overlap */
    border: none;
    outline: none;
    background-color: lightYellow;
    color: navy; 
    cursor: pointer;        /* Add a mouse pointer on hover */
    padding: 10px;          /* Some padding */
    border-radius: 10px;    /* Rounded corners */
}

#topBtn:hover { background-color: yellow /* Add a darker background on hover */
}

</style>
</head>

<body bgcolor=white style=font-size:120%>

<center>
<h2 style=font-family:sans-serif>Phemto</h2>
<small><small style=font-family:serif;>A python editor that's tiny for tiny environments</small></small>
<h1 style=font-family:sans-serif>pye</h1>
<h2 style=font-family:serif>User's Guide</h2>
</center>

<p>
Allows editing files directly on python based target boards, using a
terminal emulator such as MSWindows putty, Mac os terminal or Linux terminal.

<h3> <a href=#operations>Operations</a> include:</h3>
<ul >
<li>open (existing or new file), save, quit, &hellip;<br>
<li>goto <var>line</var>#, find, replace, &hellip;<br>
<li>create bookmark, go to previous/next bookmark.
<li>cut, copy, paste, redraw, undo, redo, &hellip;<br>
<li>indent, un-indent, comment, &hellip;<br>
<li>tab, backtab</i> and scrolling.
</ul>

<p>
<h3>Features</h3>

<ul>
<li>Action keys include: <i>^f</i>  find,  <i>^n</i> next, <i>^z</i> undo, <i> ^c</i> copy, <i> ^v</i> paste, &hellip; 
<li>Special keys, include: <i>[home]</i>, <i>[end]</i>, <i>[PgUp]</i>, &hellip;</i>
<li>Lines can be joined with cursor at the end of the line using <i>delete</i> or<br>
with cursor at the beginning with  <i>backspace</i>.
<li><i>enter</i> key inserts or splits a line with  automatic indentation.
<li>Command history permits multiple undo / redo and go to changes.
<li>Status line shows row, column, etc.
<li>Multiple files can be edited simultaneously with multiple windows.
<li>Mouse scrolling and setting the cursor.
<li>Can be used with data files or program code.
<li>Online help
</ul>

<p>
The editor operates in insert mode, that is, characters typed are inserted, control+key, alt+key and <span style=font-size:180%;vertical-align:middle;>&#x241B;</span>,key are commands.<br>
Cursor Keys, home, end, page^ &hellip; work as you would expect.


<h3>Installation</h3>
Transfer to the target board:
<ol><li>The code:
<ul>
<li> <i>pye.mpy</i> (frozen bytecode for Pyboard, ESP8266, ESP32, PyCom devices, Maixpy &hellip;) or 
<li> compiled byte code which reduces start-up time and saves memory and file space or
<li> <i>pye.py</i>  source 
</ul>
<li>The file  <i>h</i> for online help in an alternate window(optional).
</ol>
<p>

<h3 id=st>Starting <span style=font-family:monospace>pye</span></h3>
From python <i>REPL</i> prompt:<br>
<i>
>>>> from pye import pye<br>
>>>> <span style=color:silver>[</span>result =<span style=color:silver>]</span> pye(<span style=color:silver>[</span><var> object_1, object_2, &hellip;</var><span style=color:silver>[</span>,
tabsize=<var>n</var><span style=color:silver>][</span>, undo=<var>n</var> <span style=color:silver>]</span>
<!-- ,[ backup=y<span style=color:silver>]]</span> -->
)</b>
</i>

<ul>
<li>If <i>object_<var>n</var></i> is a string ( example "<i>main.py"</i> it's a file or a directory (example <i>"/flash"</i>) .

<ul>
<li> For a <b>file</b>, the content will be loaded. <br>
If the file does not exist an empty edit window is opened and it is given that name. 

<li> For a <b>directory</b>, the list of filenames will be loaded to the edit window. 

<pre><i> Directory
          /flash
          boot.py
          main.py</i></pre>

<li>For <i>pye()</i> the list of files in current directory is used.  <p>

<li>For a <b><var>list</var></b> of strings, (example ( <i>["start","stuff","end"]</i>) they will be loaded into the editing window <p>

</ul>
<li>If <b><var>object_n</var ></b> is not a string nor a list of strings, for example:<i> pye( var )</i>, ( where var is not defined )
an empty window is opened. 
</ul>

<p>
<ul> Optional named parameters:
<li><a href=#a>tabsize</a> =<var>n</var> Tab step (integer). The default is 4.
<li>undo=<var>n</var> history size (integer). The minimum size is 4.
<!-- <li>backup=y/n Adds a  '~' (tilde) to original filename before saving changes.      2.73 -->
</ul>

<!-- /* 
When the user scrolls down from the top of the document, show the button
When user clicks on button go to id=top
uses  <link rel=stylesheet href=top.css type=text/css>
*/ -->
<script>
window.onscroll = function () { scrollFunction() };
function scrollFunction() {     // hide or show button    ADD to EVERY page so only shows up on big pages!
    if    ( document.body.scrollTop > 400 || document.documentElement.scrollTop > 400)  // Safari? firefox? chrome? Ms explorer?
          { document.getElementById("topBtn").style.display="block"; }
     else { document.getElementById("topBtn").style.display="none"; }      <!-- DGG -->
                                    }
function topFunction() {
    var scroll_element = document.getElementById("top");
    scroll_element.scrollIntoView();
                                }
document.write('<button onclick="topFunction()" id=topBtn title="Go to top "><b>keys</b></button> <a id=top>');

</script>
<p>
<h3 id=operations>Keystroke commands (Operations)</h3>

Notations:
<ul><i><big>^</big></i> indicates:
<li > Hold the ctrl key while pressing the next key OR
<li> Press the <span style=font-size:180%;vertical-align:middle;>&#x241B;</span> key, then the next key.
    <small>Not with special keys i.e. [home],&hellip;</small>
</ul>
<ul><i><big>~</big></i> indicates:
<li> Hold the alt key while pressing the next key 
</ul>
<p>

<table border=1 cellpadding=5 cellspacing=0 style=font-size:120%>
<tr><th style=font-family:serif>Function<th style=font-family:serif>Keys

<tbody bgcolor=cornsilk>
 <tr><td><b>Open</b> a new file to a window                                 <th> ^o
<tr><td><b>Save</b>                                       <th> ^s
<tr><td><b>Quit</b> a window
or the line edit mode.                                                      <th> ^q <br>
<span style=font-size:190%;vertical-align:middle;>&#x241B;</span><span style=font-size:30%> </span><span 
      style=font-size:190%;vertical-align:middle;>&#x241B</span>
<tr><td><b>Previous window</b>                                 <th>  ^[PgUp]
<tr><td><b>Next window</b>                                 <th> ^[PgDn] <br> ^W

<tbody>
<tr><th  style=font-family:serif colspan=2> Inserting<br>
 <tr><td>Characters typed are inserted<td>
<tr><td>Insert spaces to the next tab stop. <small>( Default <a href=#a>tab</a> stops are every 4 columns)</small><br>
 Indent the selection.                <th> [tab]
                 
<tr><td>line <b>break</b> at the cursor position.  <small><a href=#a>Auto-indent</a> depends on setting.</small>
                                                                        <th>[enter]</b>

<tbody bgcolor=azure>

<tr><th style=font-family:serif colspan=2 > Movement <br> go to:
<tr><td><b>Top</b> of the file                                              <th> ^t<br> ^[home] 
<tr><td><b>Left</b> to the start of the previous word
skipping over to the previous line.                                         <th valign=top> ^&larr;

<tr><td><b>Start-of-line</b>  OR  <b>start-of-text</b>                  <th> [home]
<tr><td><b>Right</b> after the next word or line end,
wrapping over to the next line.                                             <th valign=top> ^&rarr;
<tr><td><b>End-of-code</b>    OR      <b>End-of-line</b>                <th> [end]


<tr><td><b>Line #</b><th> ^g
<tr><td><b>Bottom</b> of the file                                               <th> ^b <br> ^[end]</b><b>

<tr><td><b>previous Change <br>
next             </b>
                                                                                    <th> ~[home] <br>~[end]


<tr><td bgcolor=mintCream><b>Bookmark a location</b> in any window.     <th bgcolor=mintCream> ~[ins] 
<tr><td style=border-top-width:0><b>previous Bookmark<br>
next</b>                                                <th  style=border-top-width:0> ~[PgUp] <br> ~[PgDn] 

<tbody bgcolor=mintCream>

<tr><td style=border-top-width:3><b>Match bracket</b> the cursor is on.  <br>
<small>Bracket pairs are ( ), [ ], { } and &lt; > </small>                                  
                                                                        <th valign=top style=border-top-width:3> ^k<br>
<tr><td><b>Current line or selected </b> up / down with the cursor 
                                                                         <th style=white-space:nowrap;> ^&uarr; <small>/</small> ^&darr;
<tr><td><b>Cursor </b> up / down a screen                               <th> <nobr>[PgUp] / [PgDn]

<tr><td><b>Scroll</b> the window</b> up / down</b>                        <th> ^&uarr; <small>/</small>  ^&darr;






<tbody bgcolor=gainsboro>
<tr><th  style=font-family:serif colspan=2>Selecting text

<tr><td><b>Start selection </b> <br>
<small>Once selecting is started it can be extended by moving the cursor. <br></small>
<small>The selection is effected by Delete, Backspace, Copy, Cut, Paste, Tab,
Backtab, Find, Save and Replace. </small><br>

<b>End selecting</b> by pressing  <i>^L</i> or <i>^space</i> or an operation(copy, delete,...). 
                                                                                    <th> shift &rarr; <br> shift &larr;<p>
                                                                                                ^L <p>    ^space 

<tr><td><b>Select previous / next</b> word or extend the Selection.               <th> ^shift &larr; <small>/</small> ^shift &rarr;
<tr><td><b>Copy selection </b> to the clipboard                                 <th> ^c
<tr><td><b>Cut selection</b>  to the clipboard.
The selection is cleared.  <br>
<small>This implements the "Cut &amp; Paste" feature.</small>                                  <th valign=top> ^x

<tr><td><b>Paste </b> the clipboard contents at the cursor position.  <br>
If text is selected, it is replaced. <br>
In the line edit mode: paste the item under the cursor.                         <th> ^v
<tr><td><b>Move selection</b> up/ down                                          <th> ~&uarr; / ~&darr;

<tbody bgcolor=mistyrose>
<tr ><th  style=font-family:serif colspan=2>Deleting</h3>
<tr><td><b>Selection </b>                                                   <th> [del] <br> [backspace]

<tr><td><b>Char left</b> of the cursor.  <br>
Join</b> to the previous line if cursor is at the beginning of the line. <br>
                                                                             <th valign=middle> [backspace]


<tr><td><b>Char under</b> (before) the cursor. <br>
Join with the next line if cursor is at the end of the line <br>
With auto-indent, delete the leading spaces of the line.                                <th> [del]

<tr><td><b>Word</b> under the cursor or spaces up to the next non-space.                <th> ^[del]
<tr><td><b>Spaces</b> back to the previous <a href=#a>tab</a> stop</a> or non-space     <th> [backtab]
<tr><td><b>Line</b>                                                                     <th> shift[del]
<tr><td><b>Un-indent</b>  a single line  or multiple selected lines.                    <th> ^u <br>[backtab]

<tbody>
<tr><th  style=font-family:serif colspan=2>Finding

<tr><td><b>Find</b> a <a href=https://docs.micropython.org/en/latest/library/re.html>regular expression</a>. <br>
 For example <i>^def</i><sup class=h title=" the ^ here is not CTRL 
rather it is the regular expression anchor 
to beginning of the line">&dagger;</sup> finds <i>def</i> at the beginning of a line.<br>
Skips a selection.<br>
Case sensitivity is set by <a href=#a><i>^a</i></a>.  Stops at the end of file.<br>
The search string is remembered.                                                      <th> ^f

<tr><td><b>Next </b>find</b>                                                           <th> ^n

<tr><td><b>Find and replace</b>. Optionally:&nbsp; <code>yes, all, no</code><small>(skip)</small><code>, quit</code><br>
With a selection only the selection is searched and <code>all</code> only applies to the selection. <th> ^r <br> ^h

<tbody bgcolor=snow>
<tr><th  style=font-family:serif colspan=2>Additional Commands

<tr><td><b>Redraw</b> the screen and display file size and free space        <br> 
<small><code style=background-color:aqua>
*main.py Row: 5/116 Col: 30. 2524KB Memory free. File 213KB, 3121KB free.</code></small>
                                                                                <th> ^e
<tr><td><b>Undo</b> the last change(s).                                         <th> ^z
<tr><td><b>Redo</b>  the operation undone by Undo
immediately after Undo(s). <br>
Any change to the text invalidates the redo history.                            <th> ^y

<tr><td><b>Comment / Uncomment</b> a line or selected area.  <br>
That is: insert / remove the comment character(s) (<a href=#a>default '<i>#</i>'</a>)          <th> ^p <br> ^_

<tr id=a ><td>Adjust <b>Attributes</b> that is: those provided when <i>pye</i> was <a href=#st>started</a>. <br>
Enter y,  n, a number or several characters in comma separated fields (example:<i>y,n,4,#,n</i>) <br>
Empty field leaves the value unchanged. <p>

<ul>The defaults are :<br>
<li>auto-indent: y <br>
<li>search case sensitive: n<br>
<li>tab-size: 4 ; that is a tab stop occurs every 4 columns<br>
<li>comment string #<br>
<li>write-tabs: n <br>
<!--   no longer available <li>positioning of the cursor during vertical moves <br>
(straight vs.  following line ends). 
-->
<th>^a
</ul>


<tbody bgcolor=linen>
<tr><th  style=font-family:serif colspan=3> Mouse Actions
<tr><td>Set the cursor.                                       <td>Button 1

<tr><td>Set / Clear highlighting.                             <td>Double click<br>Button 1
<tr><td>Find and open a directory window                      <td> button 2
<tr><td style=border-top-width:0>&nbsp;&nbsp;&nbsp;&nbsp;Search                       <td style=border-top-width:0>button1
<tr><td style=border-top-width:0>&nbsp;&nbsp;&nbsp;&nbsp;Open file                       <td style=border-top-width:0>button1


<tr><td>Scroll Up / Down the screen content by 3 lines per tick. <td>Scroll Wheel

</table>
<p>





<h2>Additional notes</h2>

<p>
<h3>Status line</h3>
<table><tr><td>
<i style=background-color:aqua>*main.py Row: 5/116 Col: 30 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</i><br>
^- asterisk indicates window contents have been changed.
</table>
<p>
For online help use <i>^oh</i> to open the file <i>h</i> in a new window and use <i>^w</i>
to switch between helpfile and editing window.

<p>

<h3>Opening Files</h3>
When opening a new window the filename will be prompted for. <br>
If the name is empty, an empty window will be opened. <br>
If the file cannot be loaded (for example it does not exist), an empty window with that name will be opened. <br>
If the name is a directory a list of filenames will be loaded.

<p>

<h3>Exiting</h3>

When saving, the content is written to a temporary file (basename + ?.pyetmp?) then it is
renamed to the filename. <br>
When saving an unnamed window, the filename will be prompted for. <br>
If the filename is invalid, the temporary file will have the content. <br>
After saving the window will be named as the saved file, which acts as Save-as.<br>

<p>
For quit, if the edited text was changed, confirmation is asked for. <p>

When the last window is closed, the pye terminates providing  the return value: 

<table border=1 cellpadding=3 cellspacing=0>
<tr><th>Editing                      <th> Return Value
<tr><td>&nbsp;&nbsp;file<td>&nbsp; name of the file 
<tr><td>&nbsp;&nbsp;list<td>&nbsp; list 
<tr><td>&nbsp;&nbsp;directory <td>&nbsp; name of the directory 
</table>

<h3>Options</h3>

The option to replace <b>all</b> sequences of spaces <b>by
tabs</b>, tab size 8. If the initial file contained tab characters, this is the default. 
When reading files, tabs are replaced by spaces, tab size 8, and white space at the end of a line is discarded. <p>

<p>
The undo stack size per window can be set <i>pye()</i> default: micro 50, PC systems 500.


<p>
<h3>PC Usage</h3>
<p>
The PC version can be called from the command line with:<br>
<code>pye.py <i style=color:silver>[</i></code><var>filename</var> , &hellip; <i style=color:silver>]</i></code>

<p>
Using <code>python3 pye.py <i style=color:silver>[</i></code><var>filename</var> , &hellip; <i style=color:silver>]</i></code> content can be redirected or pipe'd to pye.

<p>

<h3>Internals</h3>

<p >
Uses stdin/stdout on the MicroPython boards.
<h3>Board specific information</h3>
<p>
<i>WiPy1</i>: <em>only</em> works only on a Telnet session with the UART connection closed.<br>
<i>ESP8266</i>: <em>only</em> the frozen bytecode variant can be used.<br>

<h3>Memory Considerations</h3>
<p>
The size of a file that can be edited is limited by the memory of the target board. <br>
Files up to about 13kb on ESP8266 and 68kb on PyBoard should fit. <br>
REDRAW updates available memory show in the status line.
In addition to the file, clipboard and especially undo consume memory. <br>
The undo stack can be limited in the call to <i>pye</i> using <i>undo=<var>n</var></i>. <br>
The clipboard size can be reduced by copying a single line into it. <br>

<p>
When saving a file on PyBoard, the changes may not
be visible in the file system of a connected PC until you disconnect and reconnect the Pyboard drive. <br>
See also the related discussion in the MicroPython Forum.

<p >
Saving to the internal flash file system of PyBoard is slow.
<p>

In some cases, Escape seems to lock the keyboard, it unlocks by typing any alpha character.

<h2 >Terminal Emulators</h2>
<!-- see the Pyboard_Editor.7.2.doc for interals:

The keyboard mapping and screen commands expect ANSI (aka VT100) codes.  <br>


The <u>delete</u> key must be set to ASCII-Del.

<p >Empty cells are the same as puttyVT100 &amp; Xterm

<table border=1 cellspacing=0 cellpadding=3>
  
<tr> <th ><b>  Key <th align=center><b> Putty VT100 <br>&amp;<br> Xterm <th><b> Putty esc-[~ <th><b>Putty Linux <th><b>Minicom <th><b> GtkTerm <th><b> Picocom <th><b>Linux Terminal<br> TERM=ANSI 
<tr> <th> Up <th> \e[A <th> <th> <th> <th> <th> <th> 
<tr> <th> Down <th> \e[B <th> <th> <th> <th> <th> <th>
<tr> <th> Left <th> \e[D <th> <th> <th> <th> <th> <th>
<tr> <th> Right <th> \e[C <th> <th> <th> <th> <th> <th>
<tr> <th> Home <th> \e[1~ <th> <th> <th> <th> \eOH <th> \eOH <th> \e[H 
<tr> <th> End <th> \e[4~ <th> <th> <th> \eOF <th> \eOF <th> \eOF <th> \e[F 
<tr> <th> Ins <th> \e[2~ <th> <th> <th> <th> <th> <th>
<tr> <th> Del <th> \e[3~ <th> <th> <th> <th> <th> <th>
<tr> <th> PgUp <th> \e[5~ <th> <th> <th> <th> <th> <th>
<tr> <th> PgDn <th> \e[6~ <th> <th> <th> <th> <th> <th>
<tr> <th> Backspace <th> \x7f <th> <th> <th> <th> \x08 <th> <th> 
<tr> <th> Ctrl-Home <th> <th> <th> <th> \e[1;5H <th> &nbsp; <th> \e[1;5H <th> \e[1;5H 
<tr> <th> Ctrl-End <th> <th> <th> <th> \e[1;5F <th> &nbsp; <th> \e[1;5F <th> \e[1;5F 
<tr> <th> Ctrl-Del <th> <th> <th> <th> \e[3;5~ <th> \e[3;5~ <th> \e[3;5~ <th> \e[3;5~ 
<tr> <th>Tab <th> \x09 <th> <th> <th> <th> <th> <th> 
<tr> <th>BackTab <th>\e[Z <th> <th> <th> <th> <th> <th>
</table>


<br>
If the KEYMAP is too large, and you know which terminal you are working on,
delete or comment out the unneeded lines. If your terminal is different change
the control codes.

-->

<ul >
<li><b>Windows</b>
<ul>
Terminal emulators behave inconsistently.<br>
Best choices are <b>Putty, TeraTerm  or Xsh20 </u></b><br>
<li><b>Putty</b> does not report mouse actions, and does not return code for shift-arrow keys. <br>
<li><b>TeraTerm, IVT terminal and Xsh20</b> report the mouse click, but not the scroll wheel actions.<br>
<li><b>ZOC</b> reports mouse positions constantly, and <br>
sends no key codes for Home, End, PgUp, PGDn and Del. <br>
<li><b>PowerVT</b> sends no key codes for Home, End, PgUp, PGDn and Del. <br>
<li><b>Hyperterminal's</b> VT100 emulation is poor.
</ul>
<li><b>Linux</b>

<ul>
<li><b>Gnome</b> terminal sometimes does not send the first mouse wheel code, after the pointer
was moved into the window. <br>
<li><b>Mate and XFCE4</b> have slightly different keyboard mappings.<br>
<li><b> Picocom</b> sometimes sends Linux Terminal codes. 
</ul>

<li><b>Mac OS</b>
<ul>
<li>terminal
<ul>

</ul>
</ul>
</ul>
<p >
See <i style=font-weight:normal>Pyboard_Editor.doc</i> in <a href=https://github.com/robert-hh/Micropython-Editor>GitHub</a>
 for additional details.

<p align=right>
<small><small>DGerman&#x40Real-World-Systems.com version 1.5, 8/10/22 for pye version 2.77</small></small>

</body>

</html>
